Search Filters and Pagination
Search Filters
Several Assetic REST API GET endpoints allow search criteria to be entered to allow a subset of records to be returned as a list.
The parameter 'filters' is used to specify the search criteria. Filter values for string and datetime fields are encapsulated with single quotation marks ('). If the search criteria has a ' in the value, it may be escaped by encapsulating the single quotation mark with single quotation marks so that there are 3 consecutive quotation marks in place of the original 1 quotation mark. As an example to filter by the name O'Brien ,the filter string would be 'O'''Brien'.
NOTE The Search API's GET /api/v2/search and GET /api/v2/search/geojson currently use a slightly different syntax for filtering due to the search engine being used for these 2 API's. Refer to the article Using Advanced Search to bulk export for filtering syntax.
The following table lists the filter operators. Note that if the operator is not a symbol the operator is encapsulated with "~":
| Operator | Description | Example |
| "eq" or "=" | Equal to - exact match | AssetName='Billabong Reserve' or AssetName~eq~'Billabong Reserve' |
| "neq" | Not Equal To | AssetStatus~neq~'Pending' |
| "lt" or "<" | Less Than | length<50 or length~lt~50 |
| "lte" or "<=" | Less Than or Equal To | length<=50 or length~lte~50 |
| "gt" or ">" | Greater Than | length>50 or length~gt~50 |
| "gte" or ">=" | Greater Than or Equal To | length>=50 or length~gte~50 |
| "startswith" | Starts With | AssetId~startswith~'BLD' |
| "contains" | Contains | AssetName~contains~'Billabong' |
| "notsubstringof" or "doesnotcontain | Does not Contain | AssetName~notsubstringof~'Billabong' |
| "endswith" | Ends With | AssetName~endswith~'Reserve' |
More than one search filter may be applied using 'And' and 'Or' logical operators. Between each filter use "~and~" or "~or~.
It is not possible to group a set of filters and combine those filters with another group of filters that use a different logical operator.
The '~or~' operator can only be applied to a maximum of 2 values for the same field. The example below is valid
AssetId~eq~'RD124'~or~AssetId~eq~'RD125'
The following example is invalid
AssetId~eq~'RD124'~or~AssetId~eq~'RD125'~or~AssetId~eq~'RD126'
For the Asset API more than 2 values can be specified via the "In" filter.
Filter examples:
Filter 2 fields with 'and' logical operator
AssetType='Road'~and~AssetSubType='Sealed'
Filter 2 fields with 'or' logical operator
AssetType='Playground'~or~AssetType='Sporting Ground'
Filter a single field with 'and' logical operator (can act as a 'between' operator)
dateClosed~gte~'2016-09-14T11:56:29'~or~dateClosed~lte~'2016-12-14T11:56:29'
Use 'In' Filter for 'OR' queries
The 'in' search filter allows a set of records to be returned by specifying a list of values, effectively applying an 'OR' for each value. The 'in' filter is defined separately from ther search filter options as listed above, but both filters are combined when the request is applied.
Each record is encapsulated by single quotes and delimited by a comma
The following example fiters a set of assets based on a list of asset Id. It will return records where the asset Id is any of the following: 'RD124','RD125' and 'RD126'
AssetId='RD124','RD125','RD126'
Pagination
Several of the Assetic REST API GET endpoints return data as a paginated response. This may mean that not all records that satisfy the search criteria are returned by the response.
The 'pageSize' parameter is used to specify the number of records returned:
- limited to 20 records by default
- 500 records maximum if 'pageSize' parameter is specified
The 'page' parameter is used to specify which page to retrieve. This allows the next set of records to be retrieved should the number of records that satisfy the search criteria exceed the 'pageSize'. This is a new request to the Assetic REST API endpoint.
- By default 'page' is 1
- Increment the 'page' parameter by 1 and initiate a new request to get the next set of results
The response will typically be of the form (JSON) shown below:
{ "TotalResults": 1000, "TotalPages": 2, "Page": 1, "ResourceList": [ ... ] }
The 'TotalResults' is the number of records that satisfy the search criteria. In this instance there are 1000 records.
The 'TotalPages' is the total results divided by 'PageSize' in the initial request. It implies that the 'PageSize' parameter was 500 (1000/2 = 500)
'Page' is the page number returned. To get the next 500 records a new request is made with parameters of 'pageSize'=500 and 'page'=2
ResourceList is a array containing the actual data.
Order By
The result order may be set to be ascending or descending for a given field using the parameter 'sorts'. Nested ordering by specifying additional fields to sort by however is not supported.
To set the result order, specify the field name to sort an append a suffix of either '-asc' for Ascending order or '-desc' for Descending order.
For example to return records in descending order by 'AssetId' the parameter 'sorts' is set to 'AssetId-desc'.
